feat(ui5-user-settings): add UserSettingsAppearanceView components by SvilenDarvenyashki · Pull Request #12739 · UI5/webcomponents

SvilenDarvenyashki · 2025-11-30T16:44:42Z

The change introduces three new components - UserSettingsAppearanceView, UserSettingsAppearanceViewItem, and UserSettingsAppearanceViewGroup - designed to simplify building theme/appearance selection within the UserSettingsDialog. They follow the latest design guidelines and provide a ready-to-use appearance settings view that can be easily integrated or extended.

Overview

The UserSettingsAppearanceView components provide a prebuilt theme selection interface for the UserSettingsDialog, simplifying implementation and delivering a structured, predefined layout for presenting theme options with visual indicators and grouping capabilities.

Structure

UserSettingsAppearanceView (ui5-user-settings-appearance-view) is an extension of UserSettingsView that offers a ready-to-use, fixed appearance selection design aligned with the latest UI patterns, ensuring a consistent user experience for theme management.
UserSettingsAppearanceViewItem (ui5-user-settings-appearance-view-item) extends ListItemCustom to represent individual theme options with avatar icons, text labels, and selection states.
UserSettingsAppearanceViewGroup (ui5-user-settings-appearance-view-group) extends ListItemGroup to organize related themes under descriptive headers.

<ui5-user-settings-dialog id="settings" header-text="Settings" show-search-field>
    <ui5-user-settings-item icon="palette" text="Appearance" tooltip="Appearance" header-text="Appearance">
       <ui5-user-settings-appearance-view text="Themes">
          <ui5-user-settings-appearance-view-item item-key="custom_blue" text="Custom Theme Blue"></ui5-user-settings-appearance-view-item>
          <ui5-user-settings-appearance-view-item item-key="custom_dark" text="Custom Theme Dark"></ui5-user-settings-appearance-view-item>
          <ui5-user-settings-appearance-view-group header-text="SAP Horizon">
             <ui5-user-settings-appearance-view-item item-key="sap_horizon" text="SAP Morning Horizon"></ui5-user-settings-appearance-view-item>
             <ui5-user-settings-appearance-view-item item-key="sap_horizon_dark" text="SAP Evening Horizon"></ui5-user-settings-appearance-view-item>
             <ui5-user-settings-appearance-view-item item-key="sap_horizon_hcb" text="SAP Horizon High Contrast Black"></ui5-user-settings-appearance-view-item>
             <ui5-user-settings-appearance-view-item item-key="sap_horizon_hcw" text="SAP Horizon High Contrast White"></ui5-user-settings-appearance-view-item>
          </ui5-user-settings-appearance-view-group>
          <ui5-user-settings-appearance-view-group header-text="SAP Quartz">
             <ui5-user-settings-appearance-view-item item-key="sap_fiori_3" text="SAP Quartz Light"></ui5-user-settings-appearance-view-item>
             <ui5-user-settings-appearance-view-item item-key="sap_fiori_3_dark" text="SAP Quartz Dark"></ui5-user-settings-appearance-view-item>
             <ui5-user-settings-appearance-view-item item-key="sap_fiori_3_hcb" text="SAP Quartz High Contrast Black"></ui5-user-settings-appearance-view-item>
             <ui5-user-settings-appearance-view-item item-key="sap_fiori_3_hcw" text="SAP Quartz High Contrast White"></ui5-user-settings-appearance-view-item>
          </ui5-user-settings-appearance-view-group>
       </ui5-user-settings-appearance-view>
    </ui5-user-settings-item>
</ui5-user-settings-dialog>

API

UserSettingsAppearanceView

Extends: UserSettingsView

Props

text?: string - Header text for the appearance view
selected: boolean - Whether the view is currently selected (default: false)
secondary: boolean - Whether this is a secondary view (default: false)

Slots

items!: Array<UserSettingsAppearanceViewItem | UserSettingsAppearanceViewGroup> - Theme items and groups (default slot)
additionalContent?: Array - Additional content displayed above the theme list

Events
selection-change - Fired when a theme item is selected
detail.item: UserSettingsAppearanceViewItem - The selected appearance view item
cancelable: true - Event can be prevented with preventDefault()

UserSettingsAppearanceViewItem

Extends: ListItemCustom

Props

itemKey?: string - Unique identifier for the theme (default: "")
text?: string - Display text for the theme (default: "")
icon?: string - Icon name for the avatar (default: "product")
colorScheme?: string - Avatar color scheme (default: "Accent7")
selected: boolean - Whether the item is selected (managed by parent)

UserSettingsAppearanceViewGroup

Extends: ListItemGroup

Props

headerText?: string - Group header text

Slots

items!: Array - Appearance items within the group (default slot)

Test Pages

fiori/test/pages/UserSettingsDialog.html

ui5-webcomponents-bot · 2025-12-03T12:29:43Z

🧹 Preview deployment cleaned up: https://pr-12739--ui5-webcomponents.netlify.app

LilyanaOviPe

Looks good to me.

adrian-bobev · 2025-12-05T08:09:33Z

+ * Fired when a theme is selected.
+ * @public
+ */
+@event("theme-selected")


as discussed we can check with the core team about the naming of this event

adrian-bobev · 2025-12-05T08:10:24Z

+	 * @public
+	 */
+	@property()
+	selectedItemKey = "";


its better to remove this property and use the selected property of the appearance items.

Check for reference UserSettingsDialog and UserSettingsItem - the same logic applies there

adrian-bobev · 2025-12-05T08:10:53Z

+	@slot({
+		type: HTMLElement,
+	})
+	additionalContent?: Array<HTMLElement>;


maybe only content (again check with the core team)

I set it to additionalContent, because it is not the default slot while content might lead to users thinking it is the default slot.

adrian-bobev · 2025-12-05T08:11:24Z

+		this._getAllItems().forEach(item => {
+			item.selected = item.itemKey === this.selectedItemKey;
+		});
+	}


THis might be removed when selected of the items is utilizaed

adrian-bobev · 2025-12-05T08:16:53Z

+		return allItems;
+	}
+
+	_handleItemSelected = (e: CustomEvent) => {


give a type of the custom event. In that way the item will have type and no casting will be needed. Check again settings item:

e: CustomEvent

adrian-bobev · 2025-12-05T08:18:04Z

+	 * @public
+	 */
+	@property()
+	itemKey = "";


when you remove the selected item key maybe this will be remove as well

This is used to determine the theme

dobromiraboycheva · 2025-12-09T07:33:01Z

please update the demo samples: packages/website/docs/_samples/fiori/UserSettingsDialog/Basic/sample.html and packages/website/docs/_samples/patterns/UXCIntegration/Basic/sample.html

SvilenDarvenyashki · 2025-12-09T09:01:44Z

please update the demo samples: packages/website/docs/_samples/fiori/UserSettingsDialog/Basic/sample.html and packages/website/docs/_samples/patterns/UXCIntegration/Basic/sample.html

Thanks for the reminder.

ui5-webcomponents-bot · 2025-12-18T08:12:08Z

🎉 This PR is included in version v2.18.0-rc.1 🎉

The release is available on v2.18.0-rc.1

Your semantic-release bot 📦🚀

ui5-webcomponents-bot · 2026-01-05T07:14:31Z

🎉 This PR is included in version v2.18.0 🎉

The release is available on v2.18.0

Your semantic-release bot 📦🚀

feat(ui5-user-settings): add UserSettingsAppearanceView components

8676ac1

SvilenDarvenyashki requested a review from dobromiraboycheva November 30, 2025 16:44

dobromiraboycheva requested a review from adrian-bobev December 1, 2025 10:37

Merge branch 'main' into user-settings-appearance-view

09c4e11

ui5-webcomponents-bot temporarily deployed to preview December 3, 2025 12:29 Inactive

LilyanaOviPe reviewed Dec 3, 2025

View reviewed changes

adrian-bobev reviewed Dec 5, 2025

View reviewed changes

chore(ui5-user-settings): resolve comments

89a029f

ui5-webcomponents-bot temporarily deployed to preview December 8, 2025 12:47 Inactive

chore(ui5-user-settings): resolve comments

945a3a6

chore(ui5-user-settings): resolve comments

7ad0514

Merge branch 'main' into user-settings-appearance-view

bc19bf6

ui5-webcomponents-bot temporarily deployed to preview December 9, 2025 09:08 Inactive

chore(ui5-user-settings): resolve comments

12cf724

ui5-webcomponents-bot temporarily deployed to preview December 9, 2025 12:15 Inactive

Merge branch 'main' into user-settings-appearance-view

2cf21d8

ui5-webcomponents-bot temporarily deployed to preview December 9, 2025 13:38 Inactive

Merge branch 'main' into user-settings-appearance-view

8df934f

ui5-webcomponents-bot temporarily deployed to preview December 10, 2025 07:27 Inactive

dobromiraboycheva approved these changes Dec 10, 2025

View reviewed changes

chore(ui5-user-settings): added touch optimisation to appearance samples

c14de7c

ui5-webcomponents-bot temporarily deployed to preview December 10, 2025 12:06 Inactive

Merge branch 'main' into user-settings-appearance-view

d76c408

ui5-webcomponents-bot temporarily deployed to preview December 10, 2025 12:15 Inactive

Merge branch 'main' into user-settings-appearance-view

5911890

ui5-webcomponents-bot temporarily deployed to preview December 10, 2025 13:39 Inactive

SvilenDarvenyashki merged commit 5f8bf37 into main Dec 11, 2025
14 checks passed

SvilenDarvenyashki deleted the user-settings-appearance-view branch December 11, 2025 08:08

ui5-webcomponents-bot temporarily deployed to preview December 11, 2025 08:08 Inactive

ui5-webcomponents-bot added the released label Dec 18, 2025

Conversation

SvilenDarvenyashki commented Nov 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Structure

API

UserSettingsAppearanceView

UserSettingsAppearanceViewItem

UserSettingsAppearanceViewGroup

Test Pages

Uh oh!

ui5-webcomponents-bot commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

LilyanaOviPe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dobromiraboycheva commented Dec 9, 2025

Uh oh!

SvilenDarvenyashki commented Dec 9, 2025

Uh oh!

Uh oh!

ui5-webcomponents-bot commented Dec 18, 2025

Uh oh!

ui5-webcomponents-bot commented Jan 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

SvilenDarvenyashki commented Nov 30, 2025 •

edited

Loading

ui5-webcomponents-bot commented Dec 3, 2025 •

edited

Loading